<!DOCTYPE html>
<html lang="en">

<head>
	<meta charset="UTF-8"/>
	<meta name="keywords" content="syntax, file mapping, extension, shebang, interpreter"/>
	<link rel="stylesheet" href="../../Shared/sty/standard.css"/>
	<script defer src="../../Shared/js/toc.js"></script>
	
	<title>Map files to syntaxes in CotEditor on Mac</title>
</head>

<body>
<a name="syntax_file_mapping"></a>

<h1>Map files to syntaxes in CotEditor on Mac</h1>

<p>When opening a document, CotEditor detects the document type and applies the corresponding syntax automatically.</p>


<section>
<h2></h2>

<p>When opening a document, CotEditor determines which syntax to apply by aggregating the File Mapping rules configured in each syntax definition.</p>

<p>CotEditor detects the corresponding syntax in the following order:</p>

<ol>
	<li>
		<p><em>File extension</em>:</p>
		<p>Try determining syntax from the file extension. The case is basically ignored; however, case-matched ones are prioritized if multiple syntaxes are found.</p>
		<p>For example:</p>
		<ul>
			<li><p>.html → HTML</p></li>
			<li><p>.hTmL → HTML</p></li>
			<li><p>.py → Python</p></li>
		</ul>
	</li>
	
	<li>
		<p><em>Filename</em>:</p>
		<p>When there is no syntax in which the find file extension is defined or the filename doesn’t have an extension, then try determining syntax from the whole filename.</p>
		<p>For example:</p>
		<ul>
			<li><p>.htaccess → Apache</p></li>
			<li><p>makefile → Makefile</p></li>
		</ul>
	</li>
	
	<li>
		<p><em>The <span area-label="shebang">#!</area> header of the document</em>:</p>
		<p>When there is no corresponding syntax for the extension and the filename, and if the first line of the document content is the #! header, then try determining syntax from the 1# header. In this trial, the interpreter names which is defined in the syntaxes are used. The interpreter can be either the last part of the path just after <code>#!</code> or the next term to the path if the path targets <code>env</code>.</p>
		<p>For example:</p>
		<ul>
			<li><p><code>#!/usr/bin/perl</code> → Perl (interpreter: <code>perl</code>)</p></li>
			<li><p><code>#!/usr/bin/env python3</code> → Python (interpreter: <code>python3</code>)</p></li>
		</ul>
	</li>
	
	<li>
		<p><em>XML declaration</em>:</p>
		<p>When there is no corresponding syntax up to here but the file content start with an XML declaration, syntax is automatically set to XML.</p>
		<p>For example:</p>
		<ul>
			<li><p><code>&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot;?&gt;</code> → XML</p></li>
		</ul>
	</li>
	
	<li>
		<p><em>None</em>:</p>
		<p>If no appropriate syntax can be found at all, the “None” syntax would be set.</p>
	</li>
</ol>

<p>When there are multiple syntaxes in the same level like the file extension level or the filename level, custom syntaxes are prioritized over the built-in syntaxes. And yet, if there are multiple corresponding syntaxes, the firstly found syntax is used automatically.</p>
</section>


<section>
<h2>Modify file mapping</h2>

<p>To define the rules to map files for a syntax, select File Mapping from the list on the left of the syntax editor, then add file extensions, filenames, or interpreters to the lists on the right side. See <a href="syntax_definition.html">Define a syntax</a> for how to open the syntax editor.</p>
</section>


<section>
<h2>Solve file mapping conflicts</h2>

<p>There are no conflicts among the built-in syntaxes. However, if you added custom syntaxes or modified the built-in syntaxes, the file mapping can conflict. You can see the existence of mapping conflicts from the Show File Mapping Conflict command in the Action pop-up menu for the available syntaxes list in Format settings. If the menu item is dimmed, it means there is no conflict.</p>

<p>You can just leave the file mapping conflicts as long as you can open documents with your expected syntax. There is no side issue.</p>
</section>


<section id="cf">
<h2>See also</h2>
<ul>
	<li><a href="syntax_definition.html">Define a syntax</a></li>
	<li><a href="settings_format.html">Change Format settings</a></li>
</ul>
</section>

</body>
</html>
